home *** CD-ROM | disk | FTP | other *** search
/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / hp48_2 / voyager7.exe / VOYAGER.DOC < prev    next >
Text File  |  1991-02-23  |  16KB  |  506 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.                V o y a g e r   R e f e r e n c e   M a n u a l
  13.  
  14.                                Derek S. Nickel
  15.  
  16.                                    V1.0-7
  17.  
  18.                                23 February 1991
  19.     ================================================================
  20.         Overview
  21.     ================================================================
  22.  
  23.     Voyager is a tool to interactivly disassemble the memory (RAM or
  24.     ROM) in the HP 48SX.  In this context, the term disassemble is
  25.     used to refer to disassembly of both machine code (aka
  26.     unassemble) and threaded instructions (aka unthread).
  27.  
  28.     Voyager consistes of several images:
  29.  
  30.     VOYAGER.EXE    Main program
  31.     DMPTOMEM.EXE    Converts ROM dump to Voyager MEM file
  32.     BINTOMEM.EXE    Converts binary file to Voyager MEM file
  33.  
  34.     The calculator's address space in Voyager is divided into ports,
  35.     similarly to the ports in the calculator itself.  The ports are:
  36.  
  37.     Port 0: 00000-7FFFF
  38.     Port 1: 80000-BFFFF
  39.     Port 2: C0000-FFFFF
  40.  
  41.     A 'module' can be loaded into one of Voyager's ports with the
  42.     LOAD command.  The HP48 module is automatically LOADed into port
  43.     0 when you invoke Voyager.
  44.  
  45.     Each module consists of these files:
  46.  
  47.     module.MEM    Voyager MEM file (memory dump)
  48.     module.CA    Address Comments
  49.     module.CC    Code Comments
  50.     module.CAX    Index for the CA file
  51.     module.CCX    Index for the CC file
  52.  
  53.     The MEM file is required; the other files will created, if
  54.     absent.
  55.  
  56.     The MEM file is an ASCII listing of the nibbles in the module to
  57.     unthread or unassemble.  It can is produced by downloading via
  58.     the Memory Scanner or KERMIT transfer and then filtered with
  59.     either the DMPTOMEM or BINTOMEM programs.
  60.  
  61.         Two comment files are used by Voyager. Both have the same format.
  62.         Each line consists of the 5 nibble address being described,
  63.         followed by a space and the one line comment describing the
  64.     address. Lines beginning with a '-' are considered deleted.
  65.  
  66.     The CA file is the address comment file.  It provides comments
  67.         explaining the purpose of address references.  For example, the
  68.         DUP routine is at 1FB87.  Unthreading is done with the UNTHREAD
  69.     or UT commands.  Unthreading 1FB87 yields:
  70.  
  71.     Voyager> UT 1FB87
  72.     1FB87: ; *** DUP (XLIB 2 269) ***
  73.     1FB87: 02D9D ! Program
  74.     1FB8C: 18AA5 ; Save last RPL token and verify DEPTH >= 1
  75.     1FB91: 03188 ; Internal DUP
  76.     1FB96: 0312B ! End Marker
  77.     Each comment following the threaded routine address is stored in
  78.         the CA file.  Note that comments that start with a exclamation
  79.     point are generated by Voyager; Voyager knows about object
  80.     prologs and can format in-line objects (including Programs)
  81.     without assistance.  Comments that start with a semicolon are
  82.     from the CA file.  Address comments are created and deleted with
  83.     the CA and CAD commands.
  84.  
  85.     Another example: the RPL routine at 14039 is a very deep
  86.     internal routine to the code for ERRN.  It pushes the Last Error
  87.     Number as a System Binary (also called short or address by some
  88.     people).
  89.  
  90.     Voyager> UT 14039
  91.     14039: ; *** Push Last Err# as System Binary ***
  92.     14039: 1403E ! Machine Code at 1403E
  93.     1403E: 34FF607    LCHEX  706FF          ; Save Last Err#
  94.     14045: 8D3B411    GOVLNG 114B3          ; Push @C.A as new System
  95.     Binary
  96.  
  97.     114B3: ; *** Push @C.A as new System Binary ***
  98.     114B3: DA         A=C    A            
  99.     114B5: 8FB9760    GOSBVL 0679B          ; Save D,B,D1,D0 (uses C)
  100.     114BC: 130        D0=A                
  101.     114BF: 142        A=DAT0 A            
  102.     114C2: 8DC7530    GOVLNG 0357C          ; Push A as new System Binary
  103.  
  104.     The CC file is a code comment file.  It provides comments
  105.     explaining what the code at a particular address is doing.  When
  106.     the corresponding address is unassembled, the comment is
  107.     appended to the output line.  Code comments are created and
  108.     deleted with the CC and CCD commands.
  109.  
  110.     Note that GOTOs are followed.  This can be disabled or enabled
  111.     with the SET MODE NOFOLLOW and SET MODE FOLLOW commands.
  112.  
  113.     Example: the RPL routine at 03188 executes the inner-most code
  114.     for the DUP routine (i.e. after error checking and setup has
  115.     been done). It is an assembler routine with an RPL entry point,
  116.     and unthreading the entry point yields:
  117.  
  118.     Voyager> UT 03188
  119.     03188: ; *** Internal DUP ***
  120.     03188: 0318D ! Machine Code at 0318D
  121.     0318D: CF         D=D-1  A              ; room on stack?
  122.     0318F: 41F        GOC    03181          ; if not, make some
  123.     03192: 143        A=DAT1 A              ; get obj @ TOS
  124.     03195: 1C4        D1=D1- 5              ; push object again
  125.     03198: 141        DAT1=A A            
  126.     0319B: 142        A=DAT0 A              ; continue RPL
  127.     0319E: 164        D0=D0+ 5            
  128.     031A1: 808C       PC=(A)              
  129.  
  130.     The CAX and CCX files are index files for the CA and CC files.
  131.     ================================================================
  132.         Convensions
  133.     ================================================================
  134.  
  135.     UPPERCASE    Uppercase characters indicate a command or
  136.             keyword.  These can be entered as either upper
  137.             or lower case.  Most commands can be
  138.             abbreviated.
  139.  
  140.     lowercase    Lowercase is used as a placeholder for
  141.             information that you would enter.
  142.  
  143.     [optional]    Square brackets indicate an optional parameter
  144.             or keyword.
  145.  
  146.     addr        A five digit hexadecimal address address, a
  147.             "." or a "$".
  148.  
  149.             A "." means the next address or 'continue'.
  150.  
  151.             A "$" means the last specified address or
  152.             'repeat'.  The last specified address can be
  153.             either explicitly specified or implicitly
  154.             specified.
  155.  
  156.             If addr is optional and omitted, it defaults to
  157.             the next address (continue).
  158.  
  159.     addr:addr    Indicates an address range.  You may omit either
  160.             the start or end addresses.  The start address
  161.             will default to 00000.  The end address will
  162.             default to FFFFF.  You may also use the "." and
  163.             "$" as specified above.
  164.  
  165.             if you specify a single address without the
  166.             range specifier (the ":") then the range is
  167.             that single address.
  168.  
  169.             For example:    Means:
  170.             :        00000 to FFFFF
  171.             :14D20        00000 to 14A20
  172.             1175:        01175 to FFFFF
  173.             3E7:400        003E7 to 00400
  174.             2B7        002B7 only
  175.     ================================================================
  176.         Voyager Command Dictionary
  177.     ================================================================
  178.  
  179.     Quick Reference;
  180.  
  181.     CA addr text
  182.     CAD addr
  183.     CC addr text
  184.     CCD addr
  185.     CL addr
  186.     DUMP [addr]
  187.     DA [addr]
  188.     DH [addr]
  189.     DT [addr]
  190.     EXAMINE HASH_TABLE addr lib-no
  191.     EXAMINE LINK_TABLE addr lib-no
  192.     EXAMINE MESSAGE_TABLE addr lib-no
  193.     EXAMINE SHORT_LIBRARY addr
  194.     EXIT
  195.     FIND addr:addr partial-comment
  196.     HELP
  197.     LIST addr:addr
  198.     LOAD port module
  199.     MERGE port filename
  200.     SEARCH addr:addr hex-string
  201.     SET LIMIT number
  202.     SET MODE FOLLOW
  203.     SET MODE NOFOLLOW
  204.     SET MODE INFO
  205.     SET MODE NOINFO
  206.     SET MODE PAGE
  207.     SET MODE NOPAGE
  208.     SET MODE PROMPT
  209.     SET MODE NOPROMPT
  210.     SHOW LIMIT
  211.     SHOW MODES
  212.     SHOW PORTS
  213.     SHOW VERSION
  214.     SORT port
  215.     UNASSEMBLE [addr]
  216.     UA [addr]
  217.     UNCONTINUE [addr]
  218.     U [addr]
  219.     UNLOAD port
  220.     UNTHREAD [addr]
  221.     UT [addr]
  222.     ----------------------------------------------------------------
  223.     CA addr text
  224.  
  225.     Creates or replaces an Address Comment for the specified address.
  226.  
  227.     ----------------------------------------------------------------
  228.     CAD addr
  229.  
  230.     Deletes the Address Comment for the specified address.
  231.  
  232.     ----------------------------------------------------------------
  233.     CC addr text
  234.  
  235.     Creates or replaces a Code Comment for the specified address.
  236.  
  237.     ----------------------------------------------------------------
  238.     CCD addr
  239.  
  240.     Deletes the Code Comment for the specified address.
  241.  
  242.     ----------------------------------------------------------------
  243.     CL addr
  244.  
  245.     Lists the Address and Code comments for the specified address.
  246.  
  247.     ----------------------------------------------------------------
  248.     DUMP [addr]
  249.     DA [addr]
  250.     DH [addr]
  251.     DT [addr]
  252.  
  253.     Displays the contents of memory at the specified address.  The
  254.     number of lines displayed can be changed with the SET LIMIT
  255.     command.  DUMP displays the information in the current dump
  256.     mode (defaults to HEX).  DA, DH and DT set the dump mode to
  257.     ALTERNATE, HEX or TEXT and then displsy the information.
  258.  
  259.     ----------------------------------------------------------------
  260.     EXAMINE HASH_TABLE addr lib-no
  261.  
  262.     Examines the Binary Integer at the specified address as if it
  263.     were the Hash Table for the specified library.
  264.  
  265.     ----------------------------------------------------------------
  266.     EXAMINE LINK_TABLE addr lib-no
  267.  
  268.     Examines the Binary Integer at the specified address as if it
  269.     were the Link Table for the specified library.
  270.  
  271.     ----------------------------------------------------------------
  272.     EXAMINE MESSAGE_TABLE addr lib-no
  273.  
  274.     Examines the Array of String at the specified address as if it
  275.     were the Message Table for the specified library.
  276.  
  277.     ----------------------------------------------------------------
  278.     EXIT
  279.  
  280.     Exit Voyager and return to DOS.
  281.  
  282.     ----------------------------------------------------------------
  283.     FIND addr:addr partial-comment
  284.  
  285.     Searches the Address Comment files for the specified partial
  286.     comment.  The case of the comment is ignored.
  287.  
  288.     For example:  To search for all occurrences of "prolog" in the
  289.     range 2000 to 3000, you would say:
  290.  
  291.     Voyager> FIND 2000:3000 prolog
  292.  
  293.     ----------------------------------------------------------------
  294.     HELP
  295.  
  296.     Provides brief help on Voyager commands.
  297.  
  298.     ----------------------------------------------------------------
  299.     LIST addr:addr
  300.  
  301.     List the Address Comments in the specified range.
  302.  
  303.     For example: list the address comment for 3ADA.
  304.  
  305.     Voyager> LIST 3ADA
  306.  
  307.     For example: list all the address comments from 3B234 to 3DB15.
  308.  
  309.     Voyager> LIST 3B234:3DB15
  310.  
  311.     ----------------------------------------------------------------
  312.     LOAD port module
  313.  
  314.     Loads the specified module into the specified port.  If a module
  315.     has already been loaded in that port, the old module is unloaded
  316.     first.  The comment files are created if they are missing.  The
  317.     index files are automatically recreated if they are out-of-date
  318.     or missing.  The required MEM file (module.MEM) can be created
  319.     with either the BINTOMEM or DMPTOMEM programs.
  320.  
  321.     For example: load the REV module into port 1.
  322.  
  323.     Voyager> LOAD 1 REV
  324.  
  325.     ----------------------------------------------------------------
  326.     MERGE port filename
  327.  
  328.     Merges the comments in the specified file into the address
  329.     comment file for the specified port.  Only new comments are
  330.     added to the comment file.  Existing comments are not
  331.     overwritten.
  332.  
  333.     The format of the comments in the file to be merged can be up to
  334.     255 characters long and must be in this format:
  335.  
  336.     <hex-address><separator><comment>
  337.  
  338.     Where:
  339.     <hex-address> = a 1 to 5 digit hexadecimal address.
  340.     <separator> = a single character followed by optional whitespace.
  341.     <comment> = any text, up to the new-line character.
  342.  
  343.     ----------------------------------------------------------------
  344.     SEARCH addr:addr hex-string
  345.     SEARCH addr:addr ENTRY
  346.     SEARCH addr:addr PREFIX
  347.  
  348.     Search part of the memory.  Hex-string specifiers the data for
  349.     which to search.  For example, to search for references to the
  350.     internal DUP command (at address 03188), you would say:
  351.  
  352.     Voyager> SEARCH : 03188
  353.  
  354.     To search for a hex-string in Memory Scanner format (backwards),
  355.     you would prefix the hex-string with a single quote.  For
  356.     example (this is equivalent to the previous example):
  357.  
  358.     Voyager> SEARCH : '88130
  359.  
  360.     You can also search for Machine Code entry points (aka prefixed
  361.     machine code) via the PREFIX keyword (in place of hex-string).
  362.     For example, to search for Machine Code entry points in the
  363.     address range from 03000 to 04000:
  364.  
  365.     Voyager> SEARCH 3000:4000 PREFIX
  366.  
  367.     You can also search for general entry points (prefix or 02D9D)
  368.     via the ENTRY keyword.
  369.     ----------------------------------------------------------------
  370.     SET LIMIT number
  371.  
  372.     Sets the number of lines displayed by the UNASSEMBLE and DUMP
  373.     commands.  The default is ten.
  374.  
  375.     ----------------------------------------------------------------
  376.     SET MODE FOLLOW
  377.     SET MODE NOFOLLOW
  378.  
  379.     Specifieds whether or not the UNASSEMBLE command follows
  380.     absolute gotos (GOTO, GOLONG and GOVLNG).  Conditional gotos
  381.     (GOC, GONC, RTNC or RTNNC) that have a Code Comment of "BET"
  382.     (Branch Every Time) are also subject to the same logic.  The
  383.     default is FOLLOW.
  384.  
  385.     ----------------------------------------------------------------
  386.     SET MODE INFO
  387.     SET MODE NOINFO
  388.  
  389.     Specifies whether or not information (debug) messages are
  390.     displayed.  The default is NOINFO.
  391.  
  392.     ----------------------------------------------------------------
  393.     SET MODE PAGE
  394.     SET MODE NOPAGE
  395.  
  396.     Specifies whether or not Voyager pauses after a screen full has
  397.     been displayed.  The default is PAGE.
  398.  
  399.     ----------------------------------------------------------------
  400.     SET MODE PROMPT
  401.     SET MODE NOPROMPT
  402.  
  403.     Specifies whether or not the Voyager prompt is displayed.  The
  404.     default is PROMPT.
  405.  
  406.     ----------------------------------------------------------------
  407.     SHOW LIMIT
  408.  
  409.     Displays the number of lines that will be displayed by the
  410.     UNASSEMBLE and DUMP commands.
  411.  
  412.     ----------------------------------------------------------------
  413.     SHOW MODES
  414.  
  415.     Displays the various mode settings.
  416.  
  417.     ----------------------------------------------------------------
  418.     SHOW PORTS
  419.  
  420.     Displays which ports have been loaded.
  421.  
  422.     ----------------------------------------------------------------
  423.     SHOW VERSION
  424.  
  425.     Displays the software version for Voyager.
  426.  
  427.     ----------------------------------------------------------------
  428.     SORT port
  429.  
  430.     Sorts the address and code comment files for the specified port.
  431.     The files are sorted by address and the index files are
  432.     recreated.  You must fist LOAD the port before sorting it.
  433.     Sorting is not required, but it will eliminate deleted comments
  434.     and make the comment files nice and pretty for printing.
  435.  
  436.     ----------------------------------------------------------------
  437.     UNASSEMBLE [addr]
  438.     UA [addr]
  439.  
  440.     Disassembles the memory as machine code starting at the
  441.     specified address.  The number of lines displayed is specified
  442.     with the SET LIMIT command.
  443.  
  444.     ----------------------------------------------------------------
  445.     UNCONTINUE [addr]
  446.     U [addr]
  447.  
  448.     Continues disassembly based on the last mode (unassemble or
  449.     unthread).
  450.  
  451.     ----------------------------------------------------------------
  452.     UNLOAD port
  453.  
  454.     Unloads the module in the specified port.
  455.  
  456.     ----------------------------------------------------------------
  457.     UNTHREAD [addr]
  458.     UT [addr]
  459.  
  460.     Disasembles one object starting at the specified address.
  461.  
  462.     ================================================================
  463.     BINTOMEM input[.] [output[.MEM]]
  464.     (program)
  465.  
  466.     Converts a binary file into a Voyager memory dump.
  467.  
  468.     ================================================================
  469.     DMPTOMEM input[.DMP] [output[.MEM]]
  470.     (program)
  471.  
  472.     Converts a Memory Scanner dump into a Voyager memory dump.
  473.  
  474.     To generate a Memory Scanner dump:
  475.  
  476.     1) attach cables connecting the PC to the HP 48SX.
  477.  
  478.     2) set the communications port to 9600 buad.
  479.  
  480.     3) invoke KERMIT on the PC and prepare to receive data.
  481.        a) C> kermit
  482.        b) Kermit> log session hp48.dmp
  483.        c) Kermit> connect
  484.  
  485.     4) invoke the Memory Scanner on the HP 48SX:
  486.        a) enter the interactive self test test mode by pressing
  487.           [ON]/[D]
  488.        b) enter Memory Scanner mode by pressing [<-] (delete key)
  489.        c) position to address 00000 by pressing [ENTER], [/]
  490.  
  491.     5) send memory dump to the PC:
  492.        a) press [SPC].  This sends 10000 (hex) nibbles down the
  493.           "wire" to the PC at 9600 buad.
  494.        b) repeat step 5a for a total of 8 times
  495.        c) the display should show "80000:"...
  496.  
  497.     6) return the HP 48SX to normal operation by pressing [ON]/[C]
  498.  
  499.     7) finish kermit (on the PC)
  500.        a) disconnect by pressing CTRL/] "C"
  501.        b) close the memory dump and quit kermit by entering "EXIT"
  502.  
  503.     To convert this Memory Scanner dump to a Voyager memory dump:
  504.  
  505.     1) at DOS: C> dmptomem hp48
  506.